<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Using the Criteria API and Metamodel API to Create Basic Typesafe Queries - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level3"><a href="gjrij.html">Overview of the Criteria and Metamodel APIs</a></p>
<p class="toc level3"><a href="gjiup.html">Using the Metamodel API to Model Entity Classes</a></p>
<p class="toc level4"><a href="gjiup.html#gjivl">Using Metamodel Classes</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Using the Criteria API and Metamodel API to Create Basic Typesafe Queries</a></p>
<p class="toc level4"><a href="#gjivs">Creating a Criteria Query</a></p>
<p class="toc level4"><a href="#gjivq">Query Roots</a></p>
<p class="toc level4"><a href="#gjiuv">Querying Relationships Using Joins</a></p>
<p class="toc level4"><a href="#gjive">Path Navigation in Criteria Queries</a></p>
<p class="toc level4"><a href="#gjivi">Restricting Criteria Query Results</a></p>
<p class="toc level5"><a href="#gjiwn">The <tt>Expression</tt> Interface Methods</a></p>
<p class="toc level5"><a href="#gjixa">Expression Methods in the <tt>CriteriaBuilder</tt> Interface</a></p>
<p class="toc level4 tocsp"><a href="#gjixe">Managing Criteria Query Results</a></p>
<p class="toc level5"><a href="#gjiwo">Ordering Results</a></p>
<p class="toc level5"><a href="#gjixg">Grouping Results</a></p>
<p class="toc level4 tocsp"><a href="#gjivy">Executing Queries</a></p>
<p class="toc level5"><a href="#gjiur">Single-Valued Query Results</a></p>
<p class="toc level5"><a href="#gjivp">Collection-Valued Query Results</a></p>
</div>
<p class="toc level2 tocsp"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gjiup.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gkjiq.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gjivm"></a><h2>Using the Criteria API and Metamodel API to Create Basic Typesafe Queries</h2>
<p>The basic semantics of a Criteria query consists of a <tt>SELECT</tt> clause, a
<tt>FROM</tt> clause, and an optional <tt>WHERE</tt> clause, similar to a JPQL query. Criteria
queries set these clauses by using Java programming language objects, so the query
can be created in a typesafe manner.</p>



<a name="gjivs"></a><h3>Creating a Criteria Query</h3>
<a name="indexterm-1872"></a><a name="indexterm-1873"></a><p>The <tt>javax.persistence.criteria.CriteriaBuilder</tt> interface is used to construct</p>


<ul><li><p>Criteria queries</p>

</li>
<li><p>Selections</p>

</li>
<li><p>Expressions</p>

</li>
<li><p>Predicates</p>

</li>
<li><p>Ordering</p>

</li></ul>
<p>To obtain an instance of the <tt>CriteriaBuilder</tt> interface, call the <tt>getCriteriaBuilder</tt> method on
either an <tt>EntityManager</tt> or an <tt>EntityManagerFactory</tt> instance.</p>

<p>The following code shows how to obtain a <tt>CriteriaBuilder</tt> instance by using the
<tt>EntityManager.getCriteriaBuilder</tt> method.</p>

<pre>EntityManager em = ...;
CriteriaBuilder cb = em.getCriteriaBuilder();</pre><p>Criteria queries are constructed by obtaining an instance of the following interface:</p>

<pre><tt>javax.persistence.criteria.CriteriaQuery</tt></pre><p><tt>CriteriaQuery</tt> objects define a particular query that will navigate over one or more
entities. Obtain <tt>CriteriaQuery</tt> instances by calling one of the <tt>CriteriaBuilder.createQuery</tt> methods. For
creating typesafe queries, call the <tt>CriteriaBuilder.createQuery</tt> method as follows:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);</pre><p>The <tt>CriteriaQuery</tt> object&rsquo;s type should be set to the expected result type of
the query. In the preceding code, the object&rsquo;s type is set to <tt>CriteriaQuery&lt;Pet></tt>
for a query that will find instances of the <tt>Pet</tt> entity.</p>

<p>In the following code snippet, a <tt>CriteriaQuery</tt> object is created for a query
that returns a <tt>String</tt>:</p>

<pre>CriteriaQuery&lt;String> cq = cb.createQuery(String.class);</pre>

<a name="gjivq"></a><h3>Query Roots</h3>
<a name="indexterm-1874"></a><p>For a particular <tt>CriteriaQuery</tt>object, the root entity of the query, from which all
navigation originates, is called the <b>query root</b>. It is similar to the <tt>FROM</tt> clause in
a JPQL query.</p>

<p>Create the query root by calling the <tt>from</tt> method on the <tt>CriteriaQuery</tt> instance.
The argument to the <tt>from</tt> method is either the entity class or an <tt>EntityType&lt;T></tt>
instance for the entity.</p>

<p>The following code sets the query root to the <tt>Pet</tt> entity:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);</pre><p>The following code sets the query root to the <tt>Pet</tt> class by using
an <tt>EntityType&lt;T></tt> instance:</p>

<pre>EntityManager em = ...;
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet_);</pre><p>Criteria queries may have more than one query root. This usually occurs when
the query navigates from several entities.</p>

<p>The following code has two <tt>Root</tt> instances:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet1 = cq.from(Pet.class);
Root&lt;Pet> pet2 = cq.from(Pet.class);</pre>

<a name="gjiuv"></a><h3>Querying Relationships Using Joins</h3>
<a name="indexterm-1875"></a><p>For queries that navigate to related entity classes, the query must define a
join to the related entity by calling one of the <tt>From.join</tt> methods on
the query root object or another join object. The <tt>join</tt> methods are similar
to the <tt>JOIN</tt> keyword in JPQL.</p>

<p>The target of the join uses the Metamodel class of type <tt>EntityType&lt;T></tt>
to specify the persistent field or property of the joined entity.</p>

<p>The <tt>join</tt> methods return an object of type <tt>Join&lt;X, Y></tt>, where <tt>X</tt> is
the source entity and <tt>Y</tt> is the target of the join. In the
following code snippet, <tt>Pet</tt> is the source entity, and <tt>Owner</tt> is the target:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);

Root&lt;Pet> pet = cq.from(Pet.class);
Join&lt;Pet, Owner> owner = pet.join(Pet_.owners);</pre><p>Joins can be chained together to navigate to related entities of the target
entity without having to create a <tt>Join&lt;X, Y></tt> instance for each join:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
EntityType&lt;Owner> Owner_ = m.entity(Owner.class);

Root&lt;Pet> pet = cq.from(Pet.class);
Join&lt;Owner, Address> address = cq.join(Pet_.owners).join(Owner_.addresses);</pre>

<a name="gjive"></a><h3>Path Navigation in Criteria Queries</h3>
<a name="indexterm-1876"></a><a name="indexterm-1877"></a><p><tt>Path</tt> objects are used in the <tt>SELECT</tt> and <tt>WHERE</tt> clauses of a
Criteria query and can be query root entities, join entities, or other <tt>Path</tt>
objects. The <tt>Path.get</tt> method is used to navigate to attributes of the entities of
a query.</p>

<p>The argument to the <tt>get</tt> method is the corresponding attribute of the entity&rsquo;s
Metamodel class. The attribute can either be a single-valued attribute, specified by <tt>@SingularAttribute</tt>
in the Metamodel class, or a collection-valued attribute, specified by one of <tt>@CollectionAttribute</tt>,
<tt>@SetAttribute</tt>, <tt>@ListAttribute</tt>, or <tt>@MapAttribute</tt>.</p>

<p>The following query returns the names of all the pets in the
data store. The <tt>get</tt> method is called on the query root, <tt>pet</tt>, with
the <tt>name</tt> attribute of the <tt>Pet</tt> entity&rsquo;s Metamodel class, <tt>Pet_</tt> as the argument:</p>

<pre>CriteriaQuery&lt;String> cq = cb.createQuery(String.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);

Root&lt;Pet> pet = cq.from(Pet.class);
cq.select(pet.get(Pet_.name));</pre>

<a name="gjivi"></a><h3>Restricting Criteria Query Results</h3>
<a name="indexterm-1878"></a><a name="indexterm-1879"></a><p>The results of a query can be restricted on the <tt>CriteriaQuery</tt> object
according to conditions set by calling the <tt>CriteriaQuery.where</tt> method. Calling the <tt>where</tt>
method is analogous to setting the <tt>WHERE</tt> clause in a JPQL query.</p>

<p>The <tt>where</tt> method evaluates instances of the <tt>Expression</tt> interface to restrict the
results according to the conditions of the expressions. <tt>Expression</tt> instances are created by using
methods defined in the <tt>Expression</tt> and <tt>CriteriaBuilder</tt> interfaces.</p>



<a name="gjiwn"></a><h4>The <tt>Expression</tt> Interface Methods</h4>
<a name="indexterm-1880"></a><a name="indexterm-1881"></a><p>An <tt>Expression</tt> object is used in a query's <tt>SELECT</tt>, <tt>WHERE</tt>, or <tt>HAVING</tt>
clause. <a href="#gjiww">Table&nbsp;35-1</a> shows conditional methods you can use with <tt>Expression</tt> objects.</p>

<a name="gjiww"></a><p class="caption">Table&nbsp;35-1 Conditional Methods in the <tt>Expression</tt> Interface</p><table><col width="20%"><col width="79%"><tr><th align="left" valign="top" scope="column"><p>Method</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>isNull</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether an
expression is null</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>isNotNull</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether an expression is not null</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>in</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether an expression
is within a list of values</p>

</td>
</tr>
</table><p>The following query uses the <tt>Expression.isNull</tt> method to find all pets where the
<tt>color</tt> attribute is null:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.where(pet.get(Pet_.color).isNull());</pre><p>The following query uses the <tt>Expression.in</tt> method to find all brown and black
pets:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.where(pet.get(Pet_.color).in("brown", "black"));</pre><p>The <tt>in</tt> method also can check whether an attribute is a member of
a collection.</p>



<a name="gjixa"></a><h4>Expression Methods in the <tt>CriteriaBuilder</tt> Interface</h4>
<a name="indexterm-1882"></a><a name="indexterm-1883"></a><p>The <tt>CriteriaBuilder</tt> interface defines additional methods for creating expressions. These methods correspond to
the arithmetic, string, date, time, and case operators and functions of JPQL.  <a href="#gjixl">Table&nbsp;35-2</a>
shows conditional methods you can use with <tt>CriteriaBuilder</tt> objects.</p>

<a name="gjixl"></a><p class="caption">Table&nbsp;35-2 Conditional Methods in the <tt>CriteriaBuilder</tt> Interface</p><table><col width="20%"><col width="79%"><tr><th align="left" valign="top" scope="column"><p>Conditional Method</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>equal</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether two expressions
are equal</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>notEqual</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether two expressions are not equal</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>gt</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether the first numeric
expression is greater than the second numeric expression</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>ge</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether the first numeric expression
is greater than or equal to the second numeric expression</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>lt</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether the first
numeric expression is less than the second numeric expression</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>le</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether the first numeric
expression is less than or equal to the second numeric expression</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>between</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether the
first expression is between the second and third expression in value</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>like</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Tests whether the
expression matches a given pattern</p>

</td>
</tr>
</table><p>The following code uses the <tt>CriteriaBuilder.equal</tt> method:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.where(cb.equal(pet.get(Pet_.name), "Fido"));
...</pre><p>The following code uses the <tt>CriteriaBuilder.gt</tt> method:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
Date someDate = new Date(...);
cq.where(cb.gt(pet.get(Pet_.birthday), date));</pre><p>The following code uses the <tt>CriteriaBuilder.between</tt> method:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
Date firstDate = new Date(...);
Date secondDate = new Date(...);
cq.where(cb.between(pet.get(Pet_.birthday), firstDate, secondDate));</pre><p>The following code uses the <tt>CriteriaBuilder.like</tt> method:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.where(cb.like(pet.get(Pet_.name), "*do"));</pre><p>Multiple conditional predicates can be specified by using the compound predicate methods of
the <tt>CriteriaBuilder</tt> interface, as shown in <a href="#gjiwu">Table&nbsp;35-3</a>.</p>

<a name="gjiwu"></a><p class="caption">Table&nbsp;35-3 Compound Predicate Methods in the <tt>CriteriaBuilder</tt> Interface</p><table><col width="20%"><col width="79%"><tr><th align="left" valign="top" scope="column"><p>Method</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>and</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>A logical conjunction of two Boolean expressions</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>or</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>A
logical disjunction of two Boolean expressions</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>not</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>A logical negation of the given Boolean
expression</p>

</td>
</tr>
</table><p>The following code shows the use of compound predicates in queries:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Metamodel m = em.getMetamodel();
EntityType&lt;Pet> Pet_ = m.entity(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.where(cb.equal(pet.get(Pet_.name), "Fido")
    .and(cb.equal(pet.get(Pet_.color), "brown")));</pre>

<a name="gjixe"></a><h3>Managing Criteria Query Results</h3>
<a name="indexterm-1884"></a><a name="indexterm-1885"></a><p>For queries that return more than one result, it&rsquo;s often helpful to organize
those results. The <tt>CriteriaQuery</tt> interface defines the <tt>orderBy</tt> method to order query results according
to attributes of an entity. The <tt>CriteriaQuery</tt> interface also defines the <tt>groupBy</tt> method
to group the results of a query together according to attributes of an
entity, and the <tt>having</tt> method to restrict those groups according to a
condition.</p>



<a name="gjiwo"></a><h4>Ordering Results</h4>
<p>The order of the results of a query can be set by
calling the <tt>CriteriaQuery.orderBy</tt> method and passing in an <tt>Order</tt> object. <tt>Order</tt> objects
are created by calling either the <tt>CriteriaBuilder.asc</tt> or the <tt>CriteriaBuilder.desc</tt> method. The <tt>asc</tt>
method is used to order the results by ascending value of the passed
expression parameter. The <tt>desc</tt> method is used to order the results by descending
value of the passed expression parameter. The following query shows the use of
the <tt>desc</tt> method:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.select(pet);
cq.orderBy(cb.desc(pet.get(Pet_.birthday)));</pre><p>In this query, the results will be ordered by the pet&rsquo;s birthday from
highest to lowest. That is, pets born in December will appear before pets
born in May.</p>

<p>The following query shows the use of the <tt>asc</tt> method:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
Join&lt;Owner, Address> address = cq.join(Pet_.owners).join(Owner_.address);
cq.select(pet);
cq.orderBy(cb.asc(address.get(Address_.postalCode)));</pre><p>In this query, the results will be ordered by the pet owner&rsquo;s postal
code from lowest to highest. That is, pets whose owner lives in
the 10001 zip code will appear before pets whose owner lives in the
91000 zip code.</p>

<p>If more than one <tt>Order</tt> object is passed to <tt>orderBy</tt>, the precedence is
determined by the order in which they appear in the argument list of
<tt>orderBy</tt>. The first <tt>Order</tt> object has precedence.</p>

<p>The following code orders results by multiple criteria:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
Join&lt;Pet, Owner> owner = cq.join(Pet_.owners);
cq.select(pet);
cq.orderBy(cb.asc(owner.get(Owner_.lastName), owner.get(Owner_.firstName)));</pre><p>The results of this query will be ordered alphabetically by the pet owner&rsquo;s
last name, then first name.</p>



<a name="gjixg"></a><h4>Grouping Results</h4>
<p>The <tt>CriteriaQuery.groupBy</tt> method partitions the query results into groups. These groups are set
by passing an expression to <tt>groupBy</tt>:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.groupBy(pet.get(Pet_.color));</pre><p>This query returns all <tt>Pet</tt> entities and groups the results by the pet&rsquo;s
color.</p>

<p>The <tt>CriteriaQuery.having</tt> method is used in conjunction with <tt>groupBy</tt> to filter over the
groups. The <tt>having</tt> method takes a conditional expression as a parameter. By calling the
<tt>having</tt> method, the query result is restricted according to the conditional expression:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
Root&lt;Pet> pet = cq.from(Pet.class);
cq.groupBy(pet.get(Pet_.color));
cq.having(cb.in(pet.get(Pet_.color)).value("brown").value("blonde"));</pre><p>In this example, the query groups the returned <tt>Pet</tt> entities by color, as
in the preceding example. However, the only returned groups will be <tt>Pet</tt> entities
where the <tt>color</tt> attribute is set to <tt>brown</tt> or <tt>blonde</tt>. That is, no gray-colored
pets will be returned in this query.</p>



<a name="gjivy"></a><h3>Executing Queries</h3>
<a name="indexterm-1886"></a><a name="indexterm-1887"></a><p>To prepare a query for execution, create a <tt>TypedQuery&lt;T></tt> object with the type
of the query result by passing the <tt>CriteriaQuery</tt> object to <tt>EntityManager.createQuery</tt>.</p>

<p>Queries are executed by calling either <tt>getSingleResult</tt> or <tt>getResultList</tt> on the <tt>TypedQuery&lt;T></tt>
object.</p>



<a name="gjiur"></a><h4>Single-Valued Query Results</h4>
<p>The <tt>TypedQuery&lt;T>.getSingleResult</tt> method is used for executing queries that return a single result:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
...
TypedQuery&lt;Pet> q = em.createQuery(cq);
Pet result = q.getSingleResult();</pre>

<a name="gjivp"></a><h4>Collection-Valued Query Results</h4>
<a name="indexterm-1888"></a><p>The <tt>TypedQuery&lt;T>.getResultList</tt> method is used for executing queries that return a collection of
objects:</p>

<pre>CriteriaQuery&lt;Pet> cq = cb.createQuery(Pet.class);
...
TypedQuery&lt;Pet> q = em.createQuery(cq);
List&lt;Pet> results = q.getResultList();</pre>
         </div>
         <div class="navigation">
             <a href="gjiup.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gkjiq.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

